/**
 * @addtogroup ring_buffer
 * ring_buff
 * @{
 */
/**
 * @file        ring_buffer.h
 * @brief       环形缓冲区模块头文件
 * @note        提供高效的环形缓冲区数据结构，支持覆盖模式，适用于嵌入式系统数据缓存
 * @author      靳普诏(puzhao.jin@hopechart.com)
 * @date        2025/06/03
 * @version     1.0

 * @par         修改日志
 * <table>
 * <tr><th>Date         <th>Version     <th>Author      <th> Description
 * <tr><td>2025/06/03   <td>1.0         <td>靳普诏       <td> 创建初始版本
 * @copyright 杭州鸿泉物联网技术股份有限公司
 */

#ifndef _RING_BUFF_H_
#define _RING_BUFF_H_


#include "az_clib/BaseTypes.h"

#ifdef __cplusplus
extern "C"
{
#endif



/**
 * @brief 环形缓冲区控制结构体
 * @details 用于管理环形缓冲区的状态信息，包括缓冲区地址、读写位置等
 */
typedef struct TRingBufferTag TRingBuffer;

struct TRingBufferTag
{
    UInt8 *buffer_start;    /**< 缓冲区起始地址 */
    UInt32 buffer_end;      /**< 缓冲区结束地址（相对于buffer_start的偏移量） */
    UInt8 *write_pos;       /**< 写指针，指向下一个写入位置 */
    UInt8 *read_pos;        /**< 读指针，指向下一个读取位置 */
    Bool allow_overwrite;   /**< 是否允许覆盖未读数据：True=允许覆盖，False=不允许 */
    UInt8 flag_created;     /**< 创建标志：0=未初始化，1=已初始化 */
};


/**
 * @brief 创建并初始化环形缓冲区
 * @param self 环形缓冲区控制结构指针
 * @param buffer 外部提供的缓冲区地址
 * @param buffer_size 缓冲区大小（字节数）
 * @param allow_overwrite 是否允许覆盖：True=允许，False=不允许
 * @return Int32 操作结果
 *   @retval 0 成功
 *   @retval -1 参数错误（self或buffer为NULL）
 *   @retval -2 缓冲区大小无效（为0）
 * @note 
 *   - 缓冲区由外部分配，本函数只负责初始化控制结构
 *   - allow_overwrite=True时，写满后继续写入会覆盖最旧数据
 *   - allow_overwrite=False时，写满后写入操作将失败
 * @warning 外部缓冲区在环形缓冲区使用期间不能释放
 */
Int32 TRingBufferCreate(TRingBuffer *self, UInt8 *buffer, UInt32 buffer_size, Bool allow_overwrite);

/**
 * @brief 销毁环形缓冲区
 * @param self 环形缓冲区控制结构指针
 * @note 仅清理控制结构，不释放外部提供的缓冲区内存
 * @warning 调用后该环形缓冲区不可再使用，除非重新调用TRingBufferCreate
 */
void  TRingBufferDestroy(TRingBuffer *self);


/**
 * @brief 向环形缓冲区写入数据
 * @param self 环形缓冲区控制结构指针
 * @param data 待写入数据的指针
 * @param data_size 待写入数据的大小（字节数）
 * @return Int32 实际写入的字节数
 *   @retval >=0 成功写入的字节数
 *   @retval -1 参数错误（self或data为NULL）
 *   @retval -2 环形缓冲区未初始化
 * @note 
 *   - 当剩余空间不足时，根据allow_overwrite标志决定行为
 *   - allow_overwrite=True: 覆盖最旧数据，返回实际写入字节数
 *   - allow_overwrite=False: 只写入可容纳部分，返回实际写入字节数
 */
Int32 TRingBufferWrite(TRingBuffer *self, const void *data, UInt32 data_size);

/**
 * @brief 从环形缓冲区读取数据
 * @param self 环形缓冲区控制结构指针
 * @param data 读取数据的存储缓冲区指针
 * @param data_size 期望读取的数据大小（字节数）
 * @return Int32 实际读取的字节数
 *   @retval >=0 成功读取的字节数
 *   @retval -1 参数错误（self或data为NULL）
 *   @retval -2 环形缓冲区未初始化
 * @note 当可读数据不足时，只读取可用部分，返回实际读取字节数
 */
Int32 TRingBufferRead(TRingBuffer *self, void *data, UInt32 data_size);

/**
 * @brief 获取环形缓冲区已使用空间大小
 * @param self 环形缓冲区控制结构指针
 * @return Int32 已使用的字节数
 *   @retval >=0 已使用字节数
 *   @retval -1 参数错误（self为NULL）
 *   @retval -2 环形缓冲区未初始化
 */
Int32 TRingBufferGetUsedSize(TRingBuffer *self);

/**
 * @brief 获取环形缓冲区剩余可用空间大小
 * @param self 环形缓冲区控制结构指针
 * @return Int32 剩余可用字节数
 *   @retval >=0 剩余可用字节数
 *   @retval -1 参数错误（self为NULL）
 *   @retval -2 环形缓冲区未初始化
 * @note 在allow_overwrite=False模式下，此值表示还能写入的最大字节数
 */
Int32 TRingBufferGetFreeSize(TRingBuffer *self);

/**
 * @brief 获取环形缓冲区总容量
 * @param self 环形缓冲区控制结构指针
 * @return Int32 缓冲区总容量（字节数）
 *   @retval >0 缓冲区总容量
 *   @retval -1 参数错误（self为NULL）
 *   @retval -2 环形缓冲区未初始化
 */
Int32 TRingBufferGetBufferSize(TRingBuffer *self);

/**
 * @brief 清空环形缓冲区
 * @param self 环形缓冲区控制结构指针
 * @note 清空后读写指针重置到起始位置，但不清除缓冲区数据
 * @warning 调用前确保没有其他线程正在访问该缓冲区
 */
void TRingBufferClear(TRingBuffer *self);





#ifdef __cplusplus
}  ///< extern "C"
#endif

#endif  ///< _RING_BUFF_H_

/**
 * @}  Generated on "2025-06-03 22:47:59" by the tool "gen_hq_file.py >> V20231119" 
 */

